home *** CD-ROM | disk | FTP | other *** search
/ PC World Interactive 1 / PC World Interactive 1 - Nisan 1997.iso / nostalji / bbs / faq / faqfrom.txt < prev    next >
Text File  |  1995-07-14  |  11KB  |  269 lines
  1. Newsgroups: news.admin.misc,news.software.readers,news.answers
  2. Path: senator-bedfellow.mit.edu!bloom-beacon.mit.edu!news!uhog.mit.edu!news.mathworks.com!hookup!romulus.ott.hookup.net!ecicrl!clewis
  3. From: clewis@ferret.ocunix.on.ca (Chris Lewis)
  4. Subject: FAQs: A Suggested Minimal Digest Format
  5. Summary: A suggested digest format for Usenet FAQs.
  6. Message-ID: <digestfaq_805728005@ferret.ocunix.on.ca>
  7. Supersedes: <digestfaq_804518404@ferret.ocunix.on.ca>
  8. Approved: news-answers-request@mit.edu
  9. Date: Fri, 14 Jul 1995 13:20:09 GMT
  10. Expires: Fri, 11 Aug 1995 13:20:05 GMT
  11. Reply-To: digfaq@ferret.ocunix.on.ca (Digest FAQ commentary reception)
  12. Organization: Elegant Communications Inc., Ottawa, Canada
  13. Keywords: faqs digest format
  14. Followup-To: poster
  15. Lines: 251
  16. Xref: senator-bedfellow.mit.edu news.admin.misc:42851 news.software.readers:20929 news.answers:48454
  17.  
  18. Archive-name: faqs/minimal-digest-format
  19. Posting-frequency: every 20 days
  20. Last-modified: Wed Jan 25 23:54:34 EST 1995
  21.  
  22.         FAQs: A Suggested Minimal Digest Format
  23.                Chris Lewis
  24.         clewis@ferret.ocunix.on.ca
  25.  
  26.  
  27.     The latest edition of this FAQ can always be retrieved from:
  28.  
  29.     ftp://rtfm.mit.edu/pub/usenet/news.answers/faqs/minimal-digest-format
  30.  
  31. Changes: URLs are now documented in RFC1630.
  32.    
  33. ------------------------------
  34.  
  35. Subject: 1. Introduction and Intent
  36.  
  37. The intent of this FAQ is to provide current and future FAQ maintainers
  38. with a simple description of a minimal format for FAQs.  This minimal
  39. format is a simplification of RFC1153 digest format that is sufficient
  40. to be compatible with common newsreader digest handling functionality,
  41. current practise, and Thomas Fine's "FAQ digest format to HTML"
  42. converter which allows more sophisticated viewing on HTML-aware systems
  43. such as Mosaic or WWW.  There are other more sophisticated formats that
  44. you can use, but this is the simplest one that is compatible with a wide
  45. range of software that understands digest format.
  46.  
  47. This format is entirely optional.  But it is designed to give you the
  48. biggest "bang per buck" in terms of existing software compatibility and
  49. minimum effort.  If you believe that your FAQ can benefit from more
  50. sophisticated formats, by all means use them.  As such, this FAQ can be
  51. simply considered a guide on how to take advantage of some basic digest
  52. capabilities in end-user viewing software.
  53.  
  54. Rather than confuse the issue by documenting all of the variation
  55. allowed by existing practise and software, this documents a single
  56. variant.  However, it can be extended by reviewing the documentation
  57. for Thomas Fine's FAQ to HTML converter:
  58.  
  59. <http://www.cis.ohio-state.edu/hypertext/faq/usenet/faq-format/top.html>
  60.  
  61. This FAQ is written entirely in the minimal digest format, and can be
  62. used as an example.  You can skip from one section to the next
  63. by pressing ^G in many newsreaders, such as rn, trn and strn.
  64.  
  65. This FAQ describes only how FAQ sections should be delimited, and
  66. a couple of suggestions for meta-references to such things as FTP
  67. or WWW repositories in formats that other tools support.
  68.  
  69. Note to reader software implementors: you should not take this format
  70. as gospel, instead, use it as a guide to one minimal format of many
  71. more sophisticated ones.  You should really be reading RFC1153,
  72. Thomas Fine's material, and consulting news.answers for how FAQS
  73. are formatted in real life.  See "Newsreader/Converter Specifics"
  74. for descriptions of how some newsreaders work with digest-like documents.
  75.  
  76. ------------------------------
  77.  
  78. Subject: 2. Table of Contents
  79.  
  80.     1. Introduction and Intent
  81.     2. Table of Contents
  82.     3. What Should the Overall FAQ Look Like?
  83.     4. What's a Section, and How is it Formatted?
  84.     5. What is the Table of Contents Format?
  85.     6. What are External Meta References,
  86.         and What is Their Format?
  87.     7. Where Do I need to Look for Other Information?
  88.     8. Newsreader/Converter Specifics
  89.  
  90. ------------------------------
  91.  
  92. Subject: 3. What Should the Overall FAQ Look Like?
  93.  
  94. Most FAQs lend themselves to a format like:
  95.  
  96.     <news headers>
  97.     <news.answers required headers if the FAQ is registered>
  98.     <title and author>
  99.     <section>
  100.     <section>
  101.     <section>
  102.     <section>
  103.  
  104. While FAQs aren't always lists of questions and answers, they usually
  105. have "sections" of text -- whether they be sets of lists, individual
  106. Q&A's, groups of Q&A, textual sections, whatever.  The digest format
  107. is all about how these sections should be delimited for automatic parsing.
  108.  
  109. Note that this FAQ doesn't attempt to explain the news headers and
  110. news.answers subheaders.  For this, you should really consult the
  111. FAQs on how to create news.answers postings.  It's worth noting a
  112. few things here.  You should use Expires/Supersedes to manage the
  113. deletion of previous copies of your FAQ.  It is also a very good idea
  114. to use References: lines to link the parts of multi-part FAQs together
  115. so that they remain together with Usenet news readers.
  116.  
  117. ------------------------------
  118.  
  119. Subject: 4. What's a Section, and How is it Formatted?
  120.  
  121. A "section" is merely a block of text.  In many FAQs they are simply
  122. the introduction paragraph, the table of contents, and each question
  123. and answer.  Through the use of digest format, most newsreaders can
  124. skip from section to section using the convention presented here, and
  125. more sophisticated packages can hypertext them.
  126.  
  127. A "section" consists of:
  128.  
  129.     <blank line>
  130.     <string of 30 hyphens>
  131.     <blank line>
  132.     Subject: <subject line>
  133.     <additional optional RFC822-like headers>
  134.     <blank line>
  135.     <text>
  136.  
  137. Note that the string of hyphens and "Subject:" must start in column one.
  138. "Subject:" has one space or tab between it and the subject line.  If you have
  139. to put "Subject:" in and don't want it interpreted as a section header, just
  140. make sure that it isn't in column one (just like above).  If your subject
  141. line is too wide to fit in 80 columns, you can continue it onto the next
  142. lines, with whitespace at the beginning of the following lines.  Example:
  143.  
  144.     Subject: this is a long........
  145.         subject line
  146.  
  147. The subject can be any arbitrary string of text.  You may wish to use
  148. a numbering scheme, for it makes it easier for your readers to "grep"
  149. down to the precise section they want.
  150.  
  151. You can place additional RFC-like headers after the Subject, such as
  152. "From:", "Date:" etc.  Again, these headers should start in column
  153. one.  There should be no blank lines in the entire set of headers
  154. in a section.
  155.  
  156. The text is free format ASCII and may be formatted any way you wish.
  157.  
  158. Current FAQ maintainers take note: if you're already using a consistent
  159. format for your FAQ, converting to this format will often require only
  160. one or two global edit commands.
  161.  
  162. ------------------------------
  163.  
  164. Subject: 5. What is the Table of Contents Format?
  165.  
  166. The Table of Contents simply consists of the subject lines from the rest
  167. of the FAQ, excluding "Subject:", and preferably indented.  The subject lines
  168. should be exact copies of the section headers.
  169.  
  170. This is only a suggestion.  There is no existing software that parses this
  171. data.  The intent of using exactly the same strings as the subjects is
  172. so that users can use search mechanisms to find specific sections.  If the
  173. subject line is too long to fit in a table of contents line, it is suggested
  174. that you truncate it at a convenient point - the search will still work.
  175.  
  176. ------------------------------
  177.  
  178. Subject: 6. What are External Meta References,
  179.     and What is Their Format?
  180.  
  181. Many of the more sophisticated viewers can "jump" from one FAQ to the
  182. next, retrieve data via FTP, or send email simply by "pointing at"
  183. properly formatted "tags" in your FAQ.  This FAQ recommends "URL"
  184. ("Universal Resource Locator") format tags.  See Section 7 for a
  185. reference.
  186.  
  187. If your FAQ refers to a FTP-able file, use this format:
  188.  
  189.     ftp://<inet>/<str>/<str>
  190.  
  191. Where "<inet>" is the Internet domain name of the server, and the rest
  192. of the "<str>/<str>" is the file name.  If you want to refer to a directory,
  193. leave a trailing "/".
  194.  
  195. This string can be anywhere in the document, inline with text or whatever.
  196.  
  197. Similarly, for html (hypertext markup language)-compatible documents,
  198. use http://<inet>/<str>/<str>
  199.  
  200. For clarity, it's best to surround the URL with angle brackets to make
  201. it easier to parse.  This FAQ uses this convention, ie:
  202.  
  203.    <ftp://ftp.uunet.ca/distrib/chris_lewis/hp2pbm/>
  204.  
  205. One difficulty with URLs is that they're often quite long.  Do not
  206. break them in the middle, or they won't work.  It is suggested that
  207. if the URL is too long to fit, start a new line with the URL.  Even
  208. if it does look rather ugly, it's better than not working, or wrapping
  209. beyond the 80th column.
  210.  
  211. ------------------------------
  212.  
  213. Subject: 7. Where Do I need to Look for Other Information?
  214.  
  215. [These seemed relevant, but I need descriptions!]
  216. <http://www.cis.ohio-state.edu/hypertext/usenet/faq-format/www/faq.html>,
  217. <http://www.cis.ohio-state.edu/hypertext/faq/usenet/faq-format/top.html>
  218. <http://www.cis.ohio-state.edu/hypertext/faq/usenet/technical-notes/faq.html>
  219.  
  220. John E. Goodwin's <JEGOODWIN@delphi.com> "Elements of E-Text Style",
  221.  
  222. Note the specification of URLs is now to be found in rfc1630:
  223.  
  224. "Universal Resource Identifiers in WWW"  [Jun 94]
  225.  by Tim Berners-Lee <timbl@info.cern.ch>
  226.  URL <ftp://ds.internic.net/rfc/rfc1630.txt>
  227.      <ftp://ftp.isi.edu/in-notes/rfc1630.txt>
  228.      <http://info.cern.ch/hypertext/WWW/Addressing/URL/URL_Overview.html>
  229. ------------------------------
  230.  
  231. Subject: 8. Newsreader/Converter Specifics
  232.  
  233. Rn, trn, and strn "^G" functionality skips to the next occurance of
  234. "Subject:" in column one.
  235.  
  236. GNUs has two "digest" parsers.  One insists on full RFC1153 compliance
  237. (main Subject: line "digest" tokens etc.), and the other skips to lines
  238. with (at least 8?) hyphens starting in column 1.
  239.  
  240. Tin has no digest functionality at present, though, tin's author indicates
  241. willingness to add it in a way compatible with this format.  This author
  242. suggests either the "^Subject:" or "^-*" approach.
  243.  
  244. Nn triggers on Subject: plus From: which is often not applicable
  245. to FAQs.  Nn "explodes" FAQs with both Subject: and From: subheaders
  246. into individual articles.  Most nn users this author has discussed this
  247. with do not want FAQs to behave this way, which is why this format doesn't
  248. require "From:" lines.
  249.  
  250. Thomas Fine's FAQ to HTML conversion system uses a scoring system to
  251. measure compliance with the:
  252.  
  253.     <blank line>
  254.     <line of hyphens>
  255.     <blankline>
  256.     Subject: <subject>
  257.  
  258. format.  See the following for more detail:
  259.  
  260. <http://www.cis.ohio-state.edu/hypertext/faq/usenet/faq-format/top.html>
  261.  
  262. I would appreciate detail on digest/FAQ parsing in other newsreaders and
  263. conversion systems.
  264. -- 
  265. Chris Lewis: _Una confibula non sat est_
  266. Phone: Canada 613 832-0541
  267. Latest psroff: FTP://ftp.uunet.ca/distrib/chris_lewis/psroff3.0pl17/*
  268. Latest hp2pbm: FTP://ftp.uunet.ca/distrib/chris_lewis/hp2pbm/*
  269.